插件编写介绍

需要校对 这篇文章刚刚完成，还需要进一步校对和完善。请注意移除汉字的斜体效果。你可以在这里找到其他需要校对的词条。

需要帮助这篇文章需要改进。

（AddOn programming introduction）

这篇文章介绍了如何编写一个最基础的插件。和大多数编程语言教程一样，这篇文章会教你编写一个“Hello, world!”插件。

注意：插件编写是一项进阶任务。你需要能够使用电脑，包括：

要编写插件，首先要在电脑上安装好以下2个软件：

文本编辑器的作用是用来编辑纯文本（以此得名）。需要区分一下“文本编辑器”和“文字处理器”——文字处理器可以给文字加上各种格式（如粗体或斜体），因此这类软件不保存纯文本文件，而是保存文档文件。在Windows系统上，“记事本”就是一个（非常有限的）文本编辑器，而“写字板”或是微软的“Word”就是文字处理器。这里可以使用“记事本”，而不能使用“写字板”或是“Word”。

有很多种免费的文本编辑器可供选择，带有语法高亮的功能的更好。这里推荐一下几种文本编辑器：

注意：在Lua编辑器概述页面介绍了更多Lua编辑器，但是大多数功能这篇教程中不需要用到，因此这里只推荐了最基础的编辑器。

所有的插件都位于一个名为AddOns的特定文件夹中。此文件夹位于：

其中%WorldOfWarcraftFolder%代表你的电脑中魔兽世界的安装位置。一般情况下，完整路径如下所示：

如上面所说，所有插件都存放在名为AddOns的特定文件夹中，每个插件在AddOns文件夹中都有自己的目录。

要创建新的插件，执行以下步骤：

请注意，这三个文件名唯一的区别就是后缀名。这几个后缀名分别表示：

重要提示：在AddOns中建立的文件夹名称和.toc文件的名称必须匹配。

重要提示2：如果您在魔兽世界运行时将新文件（如.lua或.XML文件）添加到插件中，则需要重新启动魔兽世界，仅仅重新加载界面是不够的。但是，更改现有文件只需要重新加载界面。

接下来的步骤是使用文本编辑器编写这三个文本文件的内容。每个文件的内容将在下面几节中介绍。

这个文件将关于你的插件的信息告诉魔兽世界客户端：要加载哪些文件，以及加载它们的顺序。你可以在稍后查看TOC格式页面，了解此文件内容的所有细节信息。现在我们只是使用一些基本的东西。

使用文本编辑器，将以下内容写进HelloWorld.toc：

这些内容很好理解：

因此这段代码逐行的意思是：

关于第一行，有一些注意事项：

当您尝试按照本教程进行操作时，该值可能会发生变化，您需要输入当前值。如果正在运行魔兽世界，可以通过运行下面的命令找到这个数字：

如果不方便运行魔兽世界，可以查看已安装的其它插件的.toc文件，或者查看获取当前接口编号。

这个数字代表的是插件的用户界面版本。例如，“70300”对应魔兽世界的7.3.x版本（其中x是任意数字）。这个数字确定了该插件与哪个版本的魔兽世界兼容，如果它与暴雪的用户界面编号不匹配，这个插件将被视为过期，除非用户在登录前勾选“加载过期插件”，否则此插件就不会加载。

想知道此文件中内容的更多细节，请访问TOC格式页面。

这个文件是确定插件“做什么”的主要文件。Lua代码对游戏中发生的事情作出回应。游戏中发生的事情叫做“事件”。

有两种基本类型的事件。

这两种事件之间存在技术上的差异，随着教程的进展我们将讨论此问题。关于第一种事件的更多详细信息，请参阅事件（API），第二种请参阅Widget handlers。

重要提示：如果你不小心写了一段要运行很长时间（甚至永远持续下去）的代码，游戏将不会任何事情。游戏将会卡死，没有任何东西会移动，用户将无法再点击任何东西。这样显然属于“不好的”。

那么，如何告诉魔兽世界你对某个特定事件感兴趣？有两种方法：首先，您可以告诉魔兽世界在发生特定事件时要运行哪段代码。这被称为注册事件。其次，您可以告诉XML在界面元素被操纵时（例如点击它或将鼠标移动到其上）运行一段代码。这些响应事件运行的代码被称为“函数”（或更精确的“事件处理程序”）。

函数是完成特定目的的代码分组。一方面，魔兽世界提供了许多预定义的功能，称为“API函数”（API即Application Programming Interface，应用程序编程接口）。另一方面，您也可以创建自己的用户定义函数。

虽然Lua语言中创建函数有多种方法，但最容易理解的是这样的：

请注意，这只是定义了函数。这个函数实际上并没有运行，直到其它一段代码调用它。

有关函数的更多信息，请参阅Lua 5.1参考手册或Lua编程（第一版）。另请参阅列出更多Lua资源的Lua页面。

现在继续“Hello, World”代码势力。在HelloWorld.lua中写上如下代码：

到目前为止你应该能看懂这些代码。这个函数名为HelloWorld，有零个参数。代码部分就是print("Hello World!");。然后代码以end结尾。

这一段代码写好了，但它本身并没有用，除非有人调用这个函数。接下来是界面元素。

“界面元素”（UI Elements），或者叫“小部件”（Widgets），指的是组成用户界面的所有图形的各个小部分。魔兽世界使用XML来布置您在屏幕上看到的所有内容。另外，当事件发生在屏幕上的小部件时，可以调用事件处理程序（即函数）来执行想要的操作。我们很快就可以看到应该如何告诉魔兽世界我们感兴趣的小部件，以及我们想要通过哪个事件处理程序来处理哪些事件。

为不知道的人介绍一下：XML代表eXtensible Markup Language，即“可扩展标记语言”，意为用标签来标记内容。存在什么样的标签，以及标签如何组织，可以被定义在一个称为“XML Schema”的东西中。在我们的例子中，我们希望创建的是魔兽世界能够理解的XML文档，因此我们要使用暴雪为魔兽世界用户界面提供的XML Schema。

用这些代码来声明我们的文档使用暴雪的格式：

这些内容的确切含义超出了本教程的范围，对于大多数插件开发者来说，只要将其放入为魔兽世界用户界面创建的每一个.xml文件中。

暴雪将小部件定义在.xsd文件中，如果你解压了客户端文件，你可以在Interface/FrameXML/UI.xsd目录下找到此文件。

处理XML文件，尤其是用于魔兽世界的XML文件时，有一些大致的东西需要了解。一个“标签”的大致格式是：

每个标签必须有一个标签名，和零个或更多属性，属性对应的取值写在双引号之间。标签指的是从之间的所有内容。标签用对应结束标签来关闭（''）。标签名不能含有空格，并且大小写敏感。如“BackgroundWidgets”是一个有效的标签名，而“backgroundwidgets”是无效的。

标签和结束标签之间的所有东西是标签的“内容”，包括嵌套标签中的其它标签以及它们的内容。有一种特殊情况：如果标签没有任何内容，则可以用来简写表示，例如：

以之前插入的那段代码举例说明：代码中包含了一个名为“Ui”的标签，它有三个属性。内容将被写在第一个>和结束标签之间。

现在继续“Hello, World"的XML示例。先将之前的代码写进HelloWorld.xml：

在为插件创建框架之前，我们还需要添加简单的一行，告诉魔兽世界如何在Lua文件中找到函数。这个标签就是一个没有内容的标签（如上文所说），因此只要以/>结尾，而不需要结束标签。

魔兽世界将所有东西联系在框架上，框架层层嵌套。所以，要创建一个与魔兽世界互动的内容，就要先创建一个框架：

这个标签名为“Frame”，有一个名为“name”的属性，属性值为“HelloWorldFrame”。

这个Frame标签应该加在Ui标签的内容中。目前为止，文件中的代码如下：

不要将各种结束标签混在一起，并且缩进代码、对齐每个标签和对应的结束标签，这有利于使代码更加清晰。“Frame”标签和“Script”标签应该完全包含在“Ui”标签中间。

框架中我们可以定义的内容之一就是脚本——一段Lua代码。将脚本放在哪里决定它何时被调用。由于脚本包含在框架中，所以我们要在“Frame”标签中加入“Scipts”标签。注意与之前的“Script”标签区分——这一次的标签名多了个“s”。

各种小部件都可以发生很多种事件，想要在某种事件触发时作出动作，就要在“Scripts”标签中包含事件名。在这个例子中，我们要用到的是一个名为“OnLoad”的事件，该事件发生在小部件在界面中加载时。例如，我们要在OnLoad事件发生时运行名为HelloWorld的脚本（HelloWorld.lua）中定义的函数。

完整的HelloWorld.xml文件如下：

上面的代码中，函数HelloWorld是除了标签和属性之外唯一的内容。魔兽世界的.xml文件中往往除了标签和属性只有很小一部分代码，这些代码只能写在表示事件的标签中间。

现在可以运行这个新插件了。

现在在你的AddOns文件夹中应该有了一个HelloWorld文件夹，HelloWorld文件夹中有HelloWorld.toc、HelloWorld.lua和HelloWorld.xml三个文件，它们的内容都在上文中给出了。

现在运行魔兽世界，登陆你的账号，不过先不要选择角色。点击角色选择界面左下角红色的“插件”按钮，可以看到魔兽世界检测到的所有插件。“AddOns”文件夹中，除了以“Blizzard_”开头的文件夹都会在此显示。

你应该可以在这个列表中找到黄色名字的“HelloWorld”插件，并且此插件是被勾选的状态。如果插件名字是红色，你可能是没有更改HelloWorld.toc文件第一行中的数字，使之与客户端版本匹配。如果你没在列表里找到你的新插件，去确认一下文件路径的位置。

给Windows用户的额外提示：确认你没有将文件保存为HelloWorld.toc.txt等，因为Windows有“隐藏文件扩展名”的选项。

插件的名字默认为黄色显示。插件的名字由HelloWorld.toc中的## Title: HelloWorld!一行决定。通过.toc文件还可以改变显示的颜色、语言等。当把鼠标移到插件名字上时，会弹出一个鼠标提示，显示由## Notes: My first AddOn一行提供的备注信息，这同样可以改变颜色和语言。

关闭插件窗口，随便进入一个角色。你会看到聊天框中出现一条信息：“Hello World!”，即代表插件运行成功。